home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _D1ABDBC970E7ED742373D2AADA22C96E < prev    next >
Text File  |  2005-10-07  |  8KB  |  197 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. #ifndef APR_POLL_H
  18. #define APR_POLL_H
  19. /**
  20.  * @file apr_poll.h
  21.  * @brief APR Poll interface
  22.  */
  23. #include "apr.h"
  24. #include "apr_pools.h"
  25. #include "apr_errno.h"
  26. #include "apr_inherit.h" 
  27. #include "apr_file_io.h" 
  28. #include "apr_network_io.h" 
  29.  
  30. #if APR_HAVE_NETINET_IN_H
  31. #include <netinet/in.h>
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif /* __cplusplus */
  37.  
  38. /**
  39.  * @defgroup apr_poll Poll Routines
  40.  * @ingroup APR 
  41.  * @{
  42.  */
  43.  
  44. /**
  45.  * Poll options
  46.  */
  47. #define APR_POLLIN    0x001     /**< Can read without blocking */
  48. #define APR_POLLPRI   0x002     /**< Priority data available */
  49. #define APR_POLLOUT   0x004     /**< Can write without blocking */
  50. #define APR_POLLERR   0x010     /**< Pending error */
  51. #define APR_POLLHUP   0x020     /**< Hangup occurred */
  52. #define APR_POLLNVAL  0x040     /**< Descriptior invalid */
  53.  
  54. /**
  55.  * Pollset Flags
  56.  */
  57. #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or Removing a Descriptor is thread safe */
  58.  
  59. /** Used in apr_pollfd_t to determine what the apr_descriptor is */
  60. typedef enum { 
  61.     APR_NO_DESC,                /**< nothing here */
  62.     APR_POLL_SOCKET,            /**< descriptor refers to a socket */
  63.     APR_POLL_FILE,              /**< descriptor refers to a file */
  64.     APR_POLL_LASTDESC           /**< descriptor is the last one in the list */
  65. } apr_datatype_e ;
  66.  
  67. /** Union of either an APR file or socket. */
  68. typedef union {
  69.     apr_file_t *f;              /**< file */
  70.     apr_socket_t *s;            /**< socket */
  71. } apr_descriptor;
  72.  
  73. /** @see apr_pollfd_t */
  74. typedef struct apr_pollfd_t apr_pollfd_t;
  75.  
  76. /** Poll descriptor set. */
  77. struct apr_pollfd_t {
  78.     apr_pool_t *p;              /**< associated pool */
  79.     apr_datatype_e desc_type;   /**< descriptor type */
  80.     apr_int16_t reqevents;      /**< requested events */
  81.     apr_int16_t rtnevents;      /**< returned events */
  82.     apr_descriptor desc;        /**< @see apr_descriptor */
  83.     void *client_data;          /**< allows app to associate context */
  84. };
  85.  
  86.  
  87. /* General-purpose poll API for arbitrarily large numbers of
  88.  * file descriptors
  89.  */
  90.  
  91. /** Opaque structure used for pollset API */
  92. typedef struct apr_pollset_t apr_pollset_t;
  93.  
  94. /**
  95.  * Setup a pollset object
  96.  * @param pollset  The pointer in which to return the newly created object 
  97.  * @param size The maximum number of descriptors that this pollset can hold
  98.  * @param p The pool from which to allocate the pollset
  99.  * @param flags Optional flags to modify the operation of the pollset.
  100.  *
  101.  * @remark If flags equals APR_POLLSET_THREADSAFE, then a pollset is
  102.  * created on which it is safe to make concurrent calls to
  103.  * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from
  104.  * separate threads.  This feature is only supported on some
  105.  * platforms; the apr_pollset_create() call will fail with
  106.  * APR_ENOTIMPL on platforms where it is not supported.
  107.  */
  108. APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset,
  109.                                              apr_uint32_t size,
  110.                                              apr_pool_t *p,
  111.                                              apr_uint32_t flags);
  112.  
  113. /**
  114.  * Destroy a pollset object
  115.  * @param pollset The pollset to destroy
  116.  */
  117. APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset);
  118.  
  119. /**
  120.  * Add a socket or file descriptor to a pollset
  121.  * @param pollset The pollset to which to add the descriptor
  122.  * @param descriptor The descriptor to add
  123.  * @remark If you set client_data in the descriptor, that value
  124.  *         will be returned in the client_data field whenever this
  125.  *         descriptor is signalled in apr_pollset_poll().
  126.  * @remark If the pollset has been created with APR_POLLSET_THREADSAFE
  127.  *         and thread T1 is blocked in a call to apr_pollset_poll() for
  128.  *         this same pollset that is being modified via apr_pollset_add()
  129.  *         in thread T2, the currently executing apr_pollset_poll() call in
  130.  *         T1 will either: (1) automatically include the newly added descriptor
  131.  *         in the set of descriptors it is watching or (2) return immediately
  132.  *         with APR_EINTR.  Option (1) is recommended, but option (2) is
  133.  *         allowed for implementations where option (1) is impossible
  134.  *         or impractical.
  135.  */
  136. APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset,
  137.                                           const apr_pollfd_t *descriptor);
  138.  
  139. /**
  140.  * Remove a descriptor from a pollset
  141.  * @param pollset The pollset from which to remove the descriptor
  142.  * @param descriptor The descriptor to remove
  143.  * @remark If the pollset has been created with APR_POLLSET_THREADSAFE
  144.  *         and thread T1 is blocked in a call to apr_pollset_poll() for
  145.  *         this same pollset that is being modified via apr_pollset_remove()
  146.  *         in thread T2, the currently executing apr_pollset_poll() call in
  147.  *         T1 will either: (1) automatically exclude the newly added descriptor
  148.  *         in the set of descriptors it is watching or (2) return immediately
  149.  *         with APR_EINTR.  Option (1) is recommended, but option (2) is
  150.  *         allowed for implementations where option (1) is impossible
  151.  *         or impractical.
  152.  */
  153. APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset,
  154.                                              const apr_pollfd_t *descriptor);
  155.  
  156. /**
  157.  * Block for activity on the descriptor(s) in a pollset
  158.  * @param pollset The pollset to use
  159.  * @param timeout Timeout in microseconds
  160.  * @param num Number of signalled descriptors (output parameter)
  161.  * @param descriptors Array of signalled descriptors (output parameter)
  162.  */
  163. APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset,
  164.                                            apr_interval_time_t timeout,
  165.                                            apr_int32_t *num,
  166.                                            const apr_pollfd_t **descriptors);
  167.  
  168.  
  169. /**
  170.  * Poll the descriptors in the poll structure
  171.  * @param aprset The poll structure we will be using. 
  172.  * @param numsock The number of descriptors we are polling
  173.  * @param nsds The number of descriptors signalled.
  174.  * @param timeout The amount of time in microseconds to wait.  This is 
  175.  *                a maximum, not a minimum.  If a descriptor is signalled, we 
  176.  *                will wake up before this time.  A negative number means 
  177.  *                wait until a descriptor is signalled.
  178.  * @remark The number of descriptors signalled is returned in the third argument. 
  179.  *         This is a blocking call, and it will not return until either a 
  180.  *         descriptor has been signalled, or the timeout has expired. 
  181.  * @remark The rtnevents field in the apr_pollfd_t array will only be filled-
  182.  *         in if the return value is APR_SUCCESS.
  183.  */
  184. APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock,
  185.                                    apr_int32_t *nsds, 
  186.                                    apr_interval_time_t timeout);
  187.  
  188. /** @} */
  189.  
  190.  
  191. #ifdef __cplusplus
  192. }
  193. #endif
  194.  
  195. #endif  /* ! APR_POLL_H */
  196.  
  197.